W05-2. Docker Compose - 실습 가이드
5주차 실습: 방명록 + PostgreSQL 을 Compose 로
compose.yaml과.env를 작성하고 명령 한 줄로 웹 + DB 를 띄운다.- 방명록 글이 PostgreSQL 에 저장되어, 컨테이너를 다시 만들어도 남아 있는 것을 확인한다.
logs,exec,down,down -v의 차이를 직접 겪어 본다.- 웹을 3개로 늘려 보고 Compose 의 한계를 확인한다.
- 4주차 실습의
docker-study/guestbook폴더에app.py,requirements.txt,Dockerfile,.dockerignore가 있어야 합니다.- 없다면 4주차 실습 0 만 먼저 하세요(7분).
- Docker Desktop 실행 중
- 터미널에서
guestbook폴더로 이동:- macOS:
cd ~/docker-study/guestbook - Windows:
cd "$HOME\docker-study\guestbook"
- macOS:
- 오늘의
docker compose명령은 macOS 와 Windows 가 똑같습니다.
| 실습 | 내용 | 시간 |
|---|---|---|
| 1 | .env 와 compose.yaml 만들기 |
7분 |
| 2 | 한 줄로 띄우기 | 5분 |
| 3 | 방명록 쓰고 DB 에서 확인하기 | 7분 |
| 4 | 설정 · 코드 바꾸기 | 6분 |
| 5 | down vs down -v |
6분 |
| 6 | 웹을 3개로? (Compose 의 한계) | 4분 |
| 7 | 코드 자동 반영: compose watch |
7분 |
| 8 | 정리 | 3분 |
실습 1. .env 와 compose.yaml 만들기
VS Code 로 guestbook 폴더를 열고, 파일 두 개를 새로 만듭니다.
① .env (점으로 시작, 확장자 없음)
DB_PASSWORD=guestpw
② compose.yaml
services:
web:
build: .
image: guestbook:compose
ports:
- "8080:8000"
environment:
APP_VERSION: v1-compose
DATABASE_URL: postgresql://guest:${DB_PASSWORD}@db:5432/guestbook
depends_on:
db:
condition: service_healthy
restart: unless-stopped
db:
image: postgres:18-alpine
environment:
POSTGRES_USER: guest
POSTGRES_PASSWORD: ${DB_PASSWORD}
POSTGRES_DB: guestbook
volumes:
- db-data:/var/lib/postgresql
healthcheck:
test: ["CMD-SHELL", "pg_isready -h localhost -U guest -d guestbook"]
interval: 5s
timeout: 3s
retries: 10
restart: unless-stopped
volumes:
db-data:
③ .dockerignore 에 한 줄 추가: 맨 아래에 .env 를 추가하고 저장합니다.
__pycache__/
*.pyc
.venv/
.git/
.DS_Store
.env
비밀번호가 든
.env가 이미지 안으로 들어가지 않게 막는 것입니다.
1-1. 문법 검사
docker compose config
출력 예시 (앞부분): ${DB_PASSWORD} 자리에 guestpw 가 채워져 보이면 .env 를 잘 읽은 것입니다.
name: guestbook
services:
db:
environment:
POSTGRES_DB: guestbook
POSTGRES_PASSWORD: guestpw
POSTGRES_USER: guest
healthcheck:
test:
- CMD-SHELL
- pg_isready -h localhost -U guest -d guestbook
...
go-yaml load error in scanner at L5.C10: mapping values are not allowed in this context같은 메시지 → 5번째 줄 근처의 들여쓰기가 틀렸습니다. 공백 칸 수를 위 예시와 똑같이 맞추세요.... found character that cannot start any token→ 탭(Tab) 이 들어갔습니다. 공백으로 바꾸세요.The "DB_PASSWORD" variable is not set경고 →.env파일 이름이나 위치가 틀렸습니다(compose.yaml과 같은 폴더).name: guestbook부분은 폴더 이름입니다. 폴더 이름이 다르면 다르게 나옵니다.
실습 2. 한 줄로 띄우기
docker compose up -d
출력 예시: 처음에는 web 이미지를 빌드하고 시작합니다.
Network guestbook_default Created
Volume guestbook_db-data Created
Container guestbook-db-1 Created
Container guestbook-web-1 Created
Container guestbook-db-1 Started
Container guestbook-db-1 Waiting
Container guestbook-db-1 Healthy
Container guestbook-web-1 Started
db 시작 → Waiting(기다림) → Healthy → 그다음에 web 시작. depends_on 의 condition: service_healthy 가 동작한 것입니다.
3주차에 손으로 했던 네트워크 만들기, 볼륨 만들기, 순서 맞추기를 Compose 가 다 했습니다.
docker compose ps
출력 예시:
NAME IMAGE COMMAND SERVICE CREATED STATUS PORTS
guestbook-db-1 postgres:18-alpine "docker-entrypoint.s…" db 14 seconds ago Up 14 seconds (healthy) 5432/tcp
guestbook-web-1 guestbook:compose "gunicorn --bind 0.0…" web 17 seconds ago Up 9 seconds 0.0.0.0:8080->8000/tcp, [::]:8080->8000/tcp
| 확인할 점 | 의미 |
|---|---|
db 의 STATUS (healthy) |
healthcheck 가 통과 중 |
db 의 PORTS 5432/tcp |
컨테이너 안에서만 열려 있음. 바깥에 공개 안 됨 (3주차의 안전한 방식) |
web 의 PORTS 0.0.0.0:8080->8000/tcp |
브라우저로 접속 가능 |
실습 3. 방명록 쓰고 DB 에서 확인하기
3-1. 브라우저
http://localhost:8080 을 열면 머리글 아래에 저장소: PostgreSQL 이 보입니다. 글을 2~3개 남겨 보세요.
http://localhost:8080/readyz 도 열어 봅니다.
{"status":"ready"}
/readyz는 앱이 DB 까지 연결되는지 확인하는 주소입니다. 10주차에 다시 씁니다.
3-2. 로그 보기
docker compose logs --tail 3 web
출력 예시: 앞에 web-1 | 처럼 어느 서비스의 로그인지 표시됩니다.
web-1 | [2026-10-01 05:18:45 +0000] [1] [INFO] Using worker: gthread
web-1 | [2026-10-01 05:18:45 +0000] [7] [INFO] Booting worker with pid: 7
web-1 | [2026-10-01 05:18:45 +0000] [1] [INFO] Control socket listening at /home/appuser/.gunicorn/gunicorn.ctl
docker compose logs -f로 전체 서비스의 로그를 실시간으로 볼 수도 있습니다.Ctrl + C로 빠져나옵니다.
3-3. DB 안을 직접 들여다보기
docker compose exec db psql -U guest -d guestbook -c "SELECT id, name, body FROM messages;"
출력 예시:
id | name | body
----+--------+------------------
1 | 김수종 | Compose 로 첫 글
2 | 홍길동 | 안녕하세요
(2 rows)
브라우저에서 쓴 글이 PostgreSQL 테이블에 들어 있습니다.
docker compose exec는 컨테이너 이름(guestbook-db-1) 대신 서비스 이름(db) 으로 부를 수 있어 편합니다.
3-4. web 이 db 를 이름으로 찾는지 확인
docker compose exec web python -c "import socket; print(socket.gethostbyname('db'))"
출력 예시: 172.24.0.2 (숫자는 다를 수 있음)
db라는 서비스 이름이 IP 로 바뀌었습니다. 그래서DATABASE_URL에@db:5432라고 쓸 수 있었습니다.
실습 4. 설정 · 코드 바꾸기
4-1. 설정(환경 변수)만 바꾸기
VS Code 에서 compose.yaml 의 APP_VERSION: v1-compose 를 APP_VERSION: v1-compose-2 로 바꾸고 저장합니다.
docker compose up -d
출력 예시: 바뀐 web 만 다시 만들고, db 는 그대로 둡니다.
Container guestbook-db-1 Running
Container guestbook-web-1 Recreate
Container guestbook-web-1 Recreated
Container guestbook-db-1 Waiting
Container guestbook-db-1 Healthy
Container guestbook-web-1 Starting
Container guestbook-web-1 Started
http://localhost:8080 → 머리글이 방명록 v1-compose-2 로 바뀌었고, 남긴 글은 그대로 있습니다.
up -d 는 "현재 상태를 파일 내용에 맞춰 줘" 라는 뜻이미 떠 있으면 바뀐 것만 다시 만듭니다. 선언형 방식의 장점입니다.
4-2. 코드 바꾸기
app.py 에서 아직 글이 없습니다 가 들어간 줄의 문구를 아무렇게나 바꾸고 저장한 뒤:
docker compose up -d
→ 아무것도 다시 만들지 않습니다. Compose 는 이미 만든 이미지 guestbook:compose 를 그대로 씁니다.
docker compose up -d --build
→ 이번에는 이미지를 다시 빌드하고 web 을 다시 만듭니다.
| 바꾼 것 | 명령 |
|---|---|
compose.yaml (설정) |
docker compose up -d |
| 소스 코드 / Dockerfile | docker compose up -d --build |
실습 5. down vs down -v
5-1. down: 컨테이너는 지우고 데이터는 남긴다
docker compose down
출력 예시:
Container guestbook-web-1 Removed
Container guestbook-db-1 Removed
Network guestbook_default Removed
Volume 은 지우지 않았습니다. 확인해 봅니다.
docker volume ls --filter name=guestbook
출력 예시:
DRIVER VOLUME NAME
local guestbook_db-data
다시 올립니다.
docker compose up -d
http://localhost:8080 → 컨테이너는 새것인데 글이 그대로 있습니다. 🎉
5-2. down -v: 볼륨까지 지운다
docker compose down -v
출력 예시:
Container guestbook-web-1 Removed
Container guestbook-db-1 Removed
Volume guestbook_db-data Removed
Network guestbook_default Removed
docker compose up -d
http://localhost:8080 → 남긴 글이 하나도 없습니다. 데이터가 영구히 사라졌습니다.
down -v 는 금지어입니다DB 데이터가 통째로 사라집니다. 실습이 아니라면 쓰기 전에 반드시 백업하세요.
실습 6. 웹을 3개로? (Compose 의 한계)
방문자가 많아져서 웹을 3개로 늘리고 싶다고 해 봅시다.
docker compose up -d --scale web=3
출력 예시 (끝부분):
Error response from daemon: failed to set up container networking: driver failed programming external connectivity on endpoint guestbook-web-3 (...): Bind for 0.0.0.0:8080 failed: port is already allocated
3개가 모두 노트북의 8080 포트를 쓰려고 했기 때문입니다. 포트 하나는 컨테이너 하나만 쓸 수 있습니다.
여러 개를 띄우고, 앞에서 하나의 주소로 받아 나눠 주는 장치(로드밸런서)가 필요합니다. → Kubernetes 의 Service (8주차)
원래대로 1개로 되돌립니다.
docker compose up -d --scale web=1
docker compose ps
guestbook-web-1과guestbook-db-1만 남아 있으면 됩니다.
실습 7. 코드 자동 반영: compose watch
코드를 고칠 때마다 --build 를 치는 대신, 저장만 하면 자동으로 반영되게 할 수 있습니다(개발용 기능).
7-1. compose.yaml 에 develop 추가
web: 서비스의 restart: unless-stopped 아래에 다음을 추가합니다. 들여쓰기에 주의하세요(develop 은 restart 와 같은 칸).
restart: unless-stopped
develop:
watch:
- action: sync+restart
path: ./app.py
target: /app/app.py
- action: rebuild
path: ./requirements.txt
| 설정 | 의미 |
|---|---|
sync+restart |
app.py 를 저장하면 컨테이너 안의 /app/app.py 로 복사하고 web 을 재시작 |
rebuild |
requirements.txt 가 바뀌면 이미지를 다시 빌드 |
7-2. watch 시작
docker compose watch
출력 예시: Watch enabled 가 나오면 준비 완료입니다. 이 터미널은 그대로 둡니다.
Container guestbook-db-1 Healthy
Container guestbook-web-1 Started
Watch enabled
7-3. 코드를 고치고 저장만 하기
VS Code 에서 app.py 의 아직 글이 없습니다 가 들어간 줄의 문구를 바꾸고 저장합니다.
watch 터미널 출력 예시:
Syncing service "web" after 1 changes were detected
Container guestbook-web-1 Restarting
Container guestbook-web-1 Started
service(s) ["web"] restarted
브라우저를 새로고침하면 바뀐 문구가 보입니다. --build 없이 반영됐습니다.
7-4. watch 끝내기
watch 터미널에서 Ctrl + C 를 누릅니다.
이미지에는 반영되지 않았습니다. 실제로 확인해 보니 docker compose down 후 up 을 하면 예전 문구로 돌아갔습니다.
고친 코드를 이미지에 넣으려면 마지막에 꼭 docker compose up -d --build 를 하세요.
실습 8. 정리
docker compose down
- 볼륨은 지우지 않아도 됩니다. 6주차부터는 Kubernetes 를 쓰므로 이 Compose 환경은 더 쓰지 않습니다. 디스크를 비우고 싶다면
docker compose down -v로 지워도 됩니다. guestbook폴더의 파일(compose.yaml,.env포함)은 그대로 두세요.- Docker Hub 에
내아이디/guestbook:v1,v2가 올라가 있는지 다시 확인하세요(4주차 실습 6). 6주차에 바로 씁니다.
자주 나는 문제와 해결
| 증상 | 원인 | 해결 |
|---|---|---|
no configuration file provided: not found |
compose.yaml 이 없는 폴더에서 실행 |
cd 로 guestbook 폴더로 이동 |
go-yaml load error ... at L5.C10: mapping values are not allowed in this context |
들여쓰기 오류 (L5 = 5번째 줄) |
예시와 칸 수를 똑같이. VS Code 오른쪽 아래가 Spaces: 2 인지 확인 |
go-yaml load error ... found character that cannot start any token |
탭(Tab) 사용 | 탭을 공백으로 바꾸기 |
The "DB_PASSWORD" variable is not set. Defaulting to a blank string. |
.env 가 없거나 이름이 틀림 (.env.txt 등) |
compose.yaml 과 같은 폴더에 정확히 .env |
dependency failed to start: container guestbook-db-1 is unhealthy |
DB 가 제시간에 준비되지 못함 | docker compose logs db 로 원인 확인 후 docker compose up -d 다시 |
방명록에 Internal Server Error, 로그에 password authentication failed |
.env 의 비밀번호를 바꿨는데 예전 볼륨을 그대로 씀 |
비밀번호는 볼륨을 처음 만들 때만 적용됩니다. 실습이면 docker compose down -v 후 다시 up -d |
Bind for 0.0.0.0:8080 failed: port is already allocated |
4주차 컨테이너 등이 8080 을 쓰는 중 | docker ps 로 찾아서 지우기 (docker rm -f 이름) |
| 코드를 고쳤는데 반영이 안 됨 | 이미지를 다시 빌드하지 않음 | docker compose up -d --build |
오늘 쓴 명령어 정리
| 명령어 | 하는 일 |
|---|---|
docker compose config |
문법 검사 + 최종 설정 보기 |
docker compose up -d |
전부 실행 (바뀐 것만 다시 만듦) |
docker compose up -d --build |
이미지 다시 빌드 후 실행 |
docker compose up -d --scale web=3 |
서비스 개수 바꾸기 |
docker compose ps |
상태 보기 |
docker compose logs [-f] [--tail N] [서비스] |
로그 보기 |
docker compose exec 서비스 명령 |
서비스 안에서 명령 실행 |
docker compose watch |
저장하면 자동 반영 (개발용) |
docker compose down |
컨테이너 · 네트워크 삭제 (볼륨 유지) |
docker compose down -v |
볼륨까지 삭제 |
복습 과제
확인 퀴즈
compose.yaml의DATABASE_URL에서 DB 주소를@db:5432라고 쓸 수 있는 이유는?depends_on에condition: service_healthy를 붙이면 무엇이 달라지나요?docker compose down과docker compose down -v의 차이는?app.py를 고친 뒤docker compose up -d만 했더니 반영되지 않았습니다. 왜 그런가요?.env파일을 Git 에 올리지 않고.dockerignore에도 넣는 이유는?--scale web=3이 실패한 이유와, 이 문제를 해결하는 Kubernetes 기능은?
- Compose 가 만든 네트워크에서는 서비스 이름이 곧 주소이기 때문입니다(Docker 내장 DNS).
- db 의 healthcheck 가 성공한 뒤에 web 을 시작합니다. 조건이 없으면 db 컨테이너가 켜지기만 하면 바로 web 을 시작합니다.
down은 컨테이너와 네트워크만 지우고 볼륨(데이터)은 남깁니다.down -v는 볼륨까지 지워서 데이터가 영구히 사라집니다.up -d는 이미 만든 이미지를 그대로 쓰기 때문입니다. 코드를 이미지에 넣으려면up -d --build로 다시 빌드해야 합니다.- 비밀번호 같은 민감한 값이 저장소나 이미지에 들어가 다른 사람에게 노출되는 것을 막기 위해서입니다.
- 3개가 모두 노트북의 같은 포트(8080) 를 쓰려고 해서 충돌했습니다. Kubernetes 에서는 Deployment 로 여러 개를 띄우고 Service 가 하나의 주소로 받아 나눠 줍니다.
도전 과제 (선택)
compose.yaml에 Adminer(웹으로 DB 를 보는 도구)를 추가해 보세요. 아래를services:아래에 넣고docker compose up -d→ http://localhost:8081 에 접속합니다. 로그인 화면에서 시스템PostgreSQL, 서버db, 사용자guest, 비밀번호guestpw, 데이터베이스guestbook.adminer: image: adminer:5 ports: - "8081:8080" depends_on: - dbdocker compose ps로 3개 서비스가 모두 떠 있는 것을 확인한 뒤docker compose down으로 정리합니다.
Compose 로는 서버 한 대 안에서만 관리할 수 있었습니다. 다음 주부터는 여러 서버(노드)를 한 덩어리처럼 다루는 Kubernetes 를 시작합니다. Docker Desktop 에 Kubernetes 클러스터를 만들고, 내가 Docker Hub 에 올린 방명록을 Pod 로 띄웁니다.
네비게이션
| 이전 | 목록 | 다음 |
|---|---|---|
| ◀ 5주차 강의 노트 | 목록으로 | 6주차 강의 노트 ▶ |